---
title: "GitLab Integration"
icon: "gitlab"
---

import AddOrganizationStep from "/snippets/add-organization-step.mdx";
import { ManagingIntegration } from "/snippets/managing-integration.mdx";
import { NeedHelpFooter } from "/snippets/need-help-footer.mdx";

Connect Codemod to your GitLab repositories to enable automated code transformations across your codebase.

## Why Integrate GitLab?

Integrating Codemod with GitLab allows you to apply codemods directly to your repositories and create merge requests with automated code changes. Our GitLab integration supports GitLab.com and uses secure token-based authentication.

## Setting Up the Integration

<AddOrganizationStep />

### Step 2: Select GitLab Provider

Choose **GitLab** as your Git provider from the available options.

<img
  src="/apps/docs/images/integrations/gitlab-step-connect-dark.png"
  alt="Screenshot of the create organization page in Codemod platform with GitLab option selected"
  title="Screenshot of the create organization page in Codemod platform with GitLab option selected"
  className="hidden dark:block mx-auto"
  style={{ width:"58%" }}
/>

<img
  src="/apps/docs/images/integrations/gitlab-step-connect-light.png"
  alt="Screenshot of the create organization page in Codemod platform with GitLab option selected"
  title="Screenshot of the create organization page in Codemod platform with GitLab option selected"
  className="block dark:hidden mx-auto"
  style={{ width:"58%" }}
/>

### Step 3: Create a GitLab Access Token

Before proceeding, you'll need to create a GitLab Group Access Token. Refer to [this guide](https://docs.gitlab.com/user/group/settings/group_access_tokens/) to create a group access token. Follow these steps:

#### Creating a Group Access Token (Recommended)

<Steps>
<Step title="Navigate to your GitLab group">
  Go to GitLab.com and navigate to your group that contains the repositories you want to integrate.
</Step>

<Step title="Access token settings">
  In the left sidebar, go to **Settings** → **Access Tokens**
</Step>

<Step title="Create new token">
  1. Click **"Add new token"**
  2. Enter a name (e.g., "Codemod Integration")
  3. Set an expiration date (optional but recommended)
  4. Select the required scopes (see below)
  5. Click **"Create group access token"**
</Step>

<Step title="Copy the token">
  Copy the generated token immediately. You won't be able to see it again!
  
  <Warning>
  Make sure to copy the token right away. GitLab will only show it once for security reasons.
  </Warning>
</Step>
</Steps>

#### Alternative: Personal Access Token

If you don't have group admin permissions, you can create a [personal access token](https://gitlab.com/-/profile/personal_access_tokens) instead. However, group access tokens are recommended as they're not tied to individual users.

### Step 4: Configure Required Token Scopes

Your GitLab token must have the following scopes:

<ParamField path="read_user" type="scope" required>
Allows reading user information and group memberships
</ParamField>

<ParamField path="write_repository" type="scope" required>
Enables creating branches, commits, and merge requests
</ParamField>

<ParamField path="api" type="scope" required>
Provides full API access for repository operations
</ParamField>

<img
  src="/apps/docs/images/integrations/gitlab-step-create-token-dark.png"
  alt="Screenshot of the create token page in GitLab with the required scopes selected"
  title="Screenshot of the create token page in GitLab with the required scopes selected"
  className="hidden dark:block mx-auto"
  style={{ width:"58%" }}
/>

<img
  src="/apps/docs/images/integrations/gitlab-step-create-token-light.png"
  alt="Screenshot of the create token page in GitLab with the required scopes selected"
  title="Screenshot of the create token page in GitLab with the required scopes selected"
  className="block dark:hidden mx-auto"
  style={{ width:"58%" }}
/>

### Step 5: Complete Organization Setup

Back in Codemod, fill in the organization details:

1. **Organization Name**: Enter your organization's display name
2. **Organization Slug**: Choose a unique URL-friendly identifier
3. **GitLab Group Access Token**: Paste the token you created

<img
  src="/apps/docs/images/integrations/gitlab-step-create-org-page-dark.png"
  alt="Screenshot of Codemod organization creation form with GitLab fields"
  title="Screenshot of Codemod organization creation form with GitLab fields"
  className="hidden dark:block mx-auto"
  style={{ width:"58%" }}
/>

<img
  src="/apps/docs/images/integrations/gitlab-step-create-org-page-light.png"
  alt="Screenshot of Codemod organization creation form with GitLab fields"
  title="Screenshot of Codemod organization creation form with GitLab fields"
  className="block dark:hidden mx-auto"
  style={{ width:"58%" }}
/>

<Info>
All tokens are encrypted both in our database and during transfer to ensure maximum security.
</Info>

Click **"Create Organization"** to complete the setup.

## Using the GitLab Integration

Once connected, you can:

- Select connected repositories when running codemods
- Automatically create merge requests with your code transformations
- Configure which repositories to target for specific codemods
- Monitor the status of your automated code changes

## Managing Your Integration

### Updating Access Tokens

To update or rotate your GitLab access token:

1. Create a new token in GitLab following the same steps above
2. Go to Codemod **Settings** → **Integrations**
3. Click **Configure** next to the GitLab integration
4. Enter the new token and save

### Repository Access

The integration will have access to all repositories within the GitLab group where you created the access token. To modify access:

1. In GitLab, go to your group's **Settings** → **Access Tokens**
2. Find your Codemod token and click **Revoke** to remove access
3. Create a new token if you want to grant access to different repositories

## Security Considerations

<Warning>
Keep your GitLab access token secure and never share it publicly or commit it to version control.
</Warning>

- **Token Security**: All tokens are encrypted at rest and in transit using industry-standard encryption
- **Minimal Permissions**: Only grant the required scopes listed above
- **Regular Rotation**: Consider rotating tokens regularly for enhanced security
- **Review Access**: Regularly review which repositories have access in your GitLab group settings
- **Merge Request Review**: All code transformations are submitted as merge requests for your review before merging

### Branch Protection

We recommend enabling merge request approvals and branch protection on your main branches to ensure changes are reviewed before merging.

## Troubleshooting

<AccordionGroup>
<Accordion title="Token authentication failed">
- Verify your token has the correct scopes: `read_user`, `write_repository`, and `api`
- Check that the token hasn't expired
- Ensure you're using a group access token for the correct GitLab group
- Make sure the token wasn't revoked in GitLab
</Accordion>

<Accordion title="Cannot access repositories">
- Confirm the token belongs to a group that contains your repositories
- Check that the repositories exist and you have the necessary permissions
- Verify the group access token has sufficient permissions in the group settings
</Accordion>

<Accordion title="Merge requests not being created">
- Ensure the target branch exists and is not protected without proper permissions
- Check that the token has `write_repository` scope
- Verify there are no branch protection rules preventing the token from creating merge requests
</Accordion>
</AccordionGroup>

<ManagingIntegration provider="GitLab" />

To revoke access from GitLab's side:

1. Go to your GitLab group's **Settings** → **Access Tokens**
2. Find the Codemod token and click **Revoke**

---

<NeedHelpFooter provider="GitLab" troubleshootingText="additional troubleshooting steps" />
